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PREFACE 



Before reading this manual, you should be familiar with the BASIC-11 
language and the RT-11 system. If necessary, read the following 
manuals before reading this User's Guide: 

• BASIC-11 Language Reference Manual (DEC-11-LIBBB-A-D) 

• Introduction to RT-11 

or 

• RT-11 System User's Guide 

Most features of BASIC-ll/RT-11 V2 are the same as in other versions 
of BASIC-11. (DIGITAL'S name for a family of BASICs for the PDP-11). 
These features are described in the BASIC-11 Language Reference Manual 
(DEC-11-LIBBB-A-D) . 

This guide describes the system dependent features of BASIC-ll/RT-11. 
They are; 

• Procedure for starting BASIC 

• Effect of the CTRL/C key command 

• Accuracy of storing numbers 

• Format of error messages 

• Format of the file specification 

• Effects of parameters in the OPEN statement 

• Procedure for checking files 

• Effect of superseding files 

• Effects of the utility functions 

• Procedure for using assembly language routines 

• Procedure for terminating BASIC 

All BASIC users should read this guide excluding only Chapter 4. Only 
users who are adding assembly language routines to BASIC need to read 
Chapter 4. Chapter 4 assumes that you are an experienced RT-11 MACRO 
programmer. 

This guide assumes that you have linked BASIC according to the 
procedure described in the BASIC-ll/RT-11 Installation Guide 
(DEC-11-LIBTA-A-D) . 
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DOCUMENTATION CONVENTIONS 



This section describes the documentation conventions, notations, and 
symbols used throughout this manual. 

The following symbols denote special terminal keys that you will use 
frequently when using BASIC. 

Symbol Meaning 

(cTRL/x) While pressing the CTRL key, type the letter indicated 
after the slash, 

<bM) Type the RETURN key. 

dE) Type the ESCAPE key (ALTMODE on some terminals). 

(eE) Type the DELETE key (RUBOUT on some terminals). 

In addition, this manual uses certain conventions when describing the 
format of statements, functions, and commands. 



These are: 

Convention 



[ ] 



Items in 
capital 
letters and 
special 
symbols 



Meaning 

The enclosed elements are optional. For example; 

|_LEtJ variable=expression 

A choice of one element among two or more 
possibilities, for example: 

^THEN statement ) 
IF relational expression<THEN line number > 

(go to line number) 

Preceding element can be repeated as indicated. 
For example: 

line number CL0SE#exprl,#expr2, . . . 

Type these elements exactly as they appear in the 
format, for example: 

LET 
RUN 



Items in capital letters are called keywords. 

Items in Replace these elements according to the 
lower case description provided in text. See below for list 
letters of commonly used lower case items. 

This list describes some lower case items commonly used in format 
descriptions. The general meaning of each item is given. Unless a 
specific format description places restrictions on an item, its 
general meaning applies. See the BASIC-11 Language Reference Manual 
for more information on these items. 



VI 



Lower Case Abbreviation Meaning 

Item 

expression expr Any valid BASIC-11 expression. 

It is always a numeric 
expression unless the 
description specifically states 
that it can be a numeric or 
string expression. For 
example: (5*SIN(X))"Y 

file specification A file specification as 

described in Section 2.1 

integer int Any positive integer number 

constant or any positive 
numeric constant that could be 
an integer if a percent sign 
were put after it. For 
example: 5%, 3%, 2, 7 

line number Any valid line number. For 

example: 10, 100, 32767 

string Any string expression. For 

example: 

"ABC", C$+SEG$(A$,3,4) 

variable var A floating point, integer or 

string variable. 

If more than one lower case word appears in a format, the words are 
numbered 1, 2, 3, etc. For example: 

CLOSE #exprl,#expr2,#expr3,. . . 

Throughout this manual, the term BASIC means BASIC-11 or 
BASIC-ll/RT-11. 

To differentiate between what BASIC prints and what you type, the user 
type-in is printed in red ink. For example: 

RUNNH 

WHAT NUMBERS? SvlO 
THE SUM IS 15 

READY 

All user type-in is terminated by the RETURN key unless the text 
indicates a different terminator. 
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CHAPTER 1 
GETTING STARTED WITH BASIC-ll/RT-11 



1.1 OPTIONAL FEATURES 

BASIC-ll/RT-11 has numerous optional features. If you include all 
optional features, any feature described in the BASIC-11 Language 
Reference Manual or in this guide is available. By excluding some or 
all optional features, you can increase the amount of memory available 
for programs or have faster program execution, or both. 

BASIC-ll/RT-11 has available the following optional features: 



Statements 








CALL 








PRINT USING 








Commands 








SUB 








RESEQ 








Functions 








SQR 


SYS 


ABS 


SEG$ 


SIN 


RCTRLO 


SGN 


VAL 


COS 


ABORT 


BIN 


TRM$ 


ATN 


TTYSET 


OCT 


STR$ 


LOG 


CTRLC 


LEN 


PI 


LOGIO 


RCTRLC 


ASC 


INT 


EXP 


TAB 


CHR$ 


DAT$ 




RND 


POS 


CLK$ 



Miscellaneous 

• Double precision arithmetic 

• Long error messages 

• Exponentiation (e.g., the expression A"B) 

• Ability to run BASIC as foreground or background job 

• Features affecting program space availability and program 
execution speed 

You must specify the inclusion or exclusion of some optional features 
at BASIC linking time. Others you select at BASIC run time. The 
features you can choose when you link BASIC are: 
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• All optional statements 

• All optional commands 

• SQR, SIN, COS, ATN, EXP, LOG, and LOGIO functions 

• All miscellaneous optional features 

The features you can choose at run time are the following optional 
functions: 

SYS ABS SEG$ 

RCTRLO SGN VAL 

ABORT BIN TRM$ 

TTYSET OCT STR$ 

CTRLC LEN PI 

RCTRLC ASC INT 

TAB CHR$ DAT$ 

RND POS CLK$ 

Before using BASIC you must link a version with the optional features 
you want. See the BASIC-ll/RT-11 Installation Guide for instructions 
to link BASIC and for information about allowed program size and speed 
of execution tradeoffs. 



1.2 STARTING BASIC 

You can use BASIC with either the single-job (SJ) , 

foreground/background (FB) , or extended memory (XM) RT-11 V3 monitor. 

When using the FB or XM monitor, you can run BASIC as either the 
foreground or background job. 

Before starting BASIC, you must bootstrap RT-11 and enter the DATE and 
TIME commands. See the Introduction to RT-11 for a description of 
these procedures. 



1.2.1 Running BASIC With the Single Job Monitor or as the Background Job 

To run BASIC with the SJ monitor or as the background job, enter 
either the BASIC or the RUN command. The BASIC command runs the file 
BASIC. SAV on your system device. To enter the BASIC command, type: 

.BASIC 
To use another version of BASIC, type: 

♦RUN file specification 

where: 

file specification specifies the file containing the 

version of BASIC that you want. 

For example, if you have a version of BASIC on device DXl: with file 
name BAS8K, and you want that version instead of the one in BASIC. SAV, 
you should enter: 

.RUN DX:!. SBAS8K 
If you specify a file that does not exist, RT-11 prints the message: 
?KMON-F-f-:i.:Le not found 
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If there is not enough 
messages is printed: 



room to run BASIC, one of the following 



NOT ENOUGH MEMORY FOR BASIC 

or 

? K M N ••■■ F - N (3 1 6) n o u sf h m e m o r w 

This error often results from a large foreground job that has not been 
unloaded. 

If there are no errors, BASIC prints an identifying message and 
inquires whether you want the optional functions that are selectable 
at run time. 

.BASIC 

BASIC-l :l/RT-:l.:l. V02 -xx 

OPTIONAL FUNCTIONS (ALL? NONE* OR INDIVIDUAL)? 

To include all of the optional functions, type an A. To exclude all 
of the optional functions, type an N. (You must always terminate 
input to BASIC with the RETURN key.) In response to your A or N, BASIC 
includes or excludes all the functions and then prints the READY 
message. For example: 

OPTIONAL FUNCTIONS (ALL. NONE, OR INDIVIDUAL >?A 



READY 

Typing only the RETURN key in response 
request is equivalent to typing A. 



to the optional functions 



If you want to choose among the optional functions individually, type 
an I. BASIC then prints an inquiry for each function individually. 
To include a function type a Y; otherwise type an N. Typing only the 
RETURN key in response to the function request is equivalent to typing 
Y. If you type anything else, BASIC repeats its request. After you 
have typed a Y or an N in response to each function inquiry, BASIC 
prints the READY message. For example: 



OPTIONAL FUNCTIONS (ALL.- NONE? OR INDIVIDUAL)? I 

SYS? N 

RCTRLO? N 

ABORT? N 

TTYSET? N 

CTRLC S RCTRLC? N 

TAB? Y 



Y 
Y 
Y 
Y 
Y 
N 
N 



RND? 

ABS? 

SON? 

BIN? 

OCT? 

LEN? 

ASC? 

CHR* 

POS? 

SEG*? N 

UAL? N 

TRM*? N 

STR*? N 

PI? N 



N 



N 
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INT? Y 
riAT$? N 
CLK*? N 

READY 



1.2.2 Running BASIC As the Foreground Job 

To run BASIC as the foreground job, use the FRUN command. Type: 

.FRUN file specification /NInumber. 
where: 

file specification specifies the file containing BASIC 

number is the size of the user area (i.e., the 

number of words to be reserved). It 
must be 1000. or greater. The decimal 
point identifies the number as decimal, 
not octal. 

You must specify the user area size, or else no area will be reserved 
and BASIC will not be able to run. 

The user area will actually be approximately 100 words more than you 
request. For example, the following command reserves approximately 
3100 words. 

.FRUN BASJ:C/NJ3000. 

If the file specified does not exist, RT-11 prints the message: 

? K M N • - F - F i :i. e n o t f o u i "i d 

If the number of words requested in the FRUN command is not large 
enough, BASIC prints the message: 

NOT ENOUGH MEMORY FOR BASIC 

If there are no errors, RT-11 prints a dot and the F> message to 
indicate that the next message is printed by the foreground job. 
BASIC then prints an identifying message and inquires whether you want 
the optional functions. For example: 

.FRUN BASIC/NtrjOOO. 

F> 

BASIC -ll/RT-l:l V02~xx 

OPTIONAL FUNCTIONS (ALL, NONE? OR INDIVIDUAL)? 

Type a CTRL/F and then answer the optional function inquiry as 
described in the previous section. 

NOTE 

To use a device other than the system 
device, you must load the handler before 
you run BASIC in the foreground. See 
the RT-11 System User's Guide for more 
information about foreground jobs. 

1-4 



GETTING STARTED WITH BASIC-ll/RT-11 

1.2.3 Running BASIC From an Indirect File 

You can run BASIC and answer the initial dialogue by using an indirect 
file. You can only run BASIC in this way as the background job or in 
the single job monitor. This technique is useful when you select the 
optional functions individually. 

You cannot enter any BASIC command, program line, or immediate mode 
statement through an indirect file. 

To create the indirect file, direct the editor to create a file with a 
file type .COM that contains all anticipated responses to system 
queries. For example: 

.R EDIT 

*EUIM :i: NRUN » COM ds) (US* 

*:rR BASIC 
I 

N 
N 
N 
N 
N 
N 
Y 
Y 
Y 
Y 
Y 
N 
N 
N 
N 

N 
N 
N 
N 
N 
Y 
N 
N 
(esQ (esc) 

*EX dDdigi 



To start BASIC, type an @ ("at" sign) followed by the file name. The 
complete initial dialogue is printed on the terminal. For example: 

.en I NRUN 

.R BASIC 

BAS I C- :l. :L /RT-- 1 1 ^02 -xx 

OPTIONAL FUNCTIONS (ALL? NONEi- OR INDIVIDUAL)? I 

SYS? N 

RCTRLO? N 

ABORT? N 

TTYSET? N 

CTRLC X RCTRLC? N 

TAB? N 
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RNi:i? 


Y 


ABS? 


Y 


BGN? 


Y 


BIN? 


Y 


OCT? 


Y 


LEN? 


N 


ASC? 


N 


CHR$? H 


POS? 


N 


i5E6$? N 


yAL? 


N 


TRM!li1 


> N 


STR*? N 


F'l? N 


INT? 


Y 


DAT*? N 


CLK*? N 



READY 

See the RT-11 System User's Guide 
indirect files. 



for more information' on using 



1.3 STOPPING BASIC PROGRAMS (CTRL/C COMMAND) 

To Stop execution of a BASIC program, use the CTRL/C command. If you 
type one CTRL/C, BASIC interrupts your program the next time it 
requests input. If you type two consecutive CTRL/C 's, BASIC 
interrupts your program immediately. After BASIC interrupts your 
program, it prints: 

STOP AT LINE xxxxx 

READY 



where: 

xxxxx 



is the number of the line that BASIC was executing when 
the CTRL/C command halted the program. 



However, if you were not executing a program line, BASIC prints: 

STOP 

READY 
When you type CTRL/C, the system prints "C. For example: 

10 (30, TO :l.O 
RIJNNH 

STOP AT LINE 10 
READY 



NOTE 

CTRL/C does not return 
RT-11 monitor. You 
command (see Section 
control to RT-11. 



control to the 

must type the BYE 

1.4) to return 
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1.4 TERMINATING THE SESSION (BYE COMMAND) 

To terminate a session with BASIC, type the BYE command. The BYE 
command returns control to the RT-11 monitor, which prints its 
prompting period. For example: 

BYE 



Once you have entered the BYE command you cannot use the RT-11 REENTER 
command to return to BASIC. Instead, you must restart BASIC as 
described in Section 1.2. If you want to reuse your BASIC program, 
save it before entering the BYE command. 

If you ran BASIC as the foreground job, you must unload it after you 
enter the BYE command. Type: 

.UNLOAD FG 



1.5 FLOATING POINT NUMBER PRECISION 

You can use BASIC with either single or double precision arithmetic. 
Single precision arithmetic allows floating point numbers to seven 
digits of precision. Thus, single precision BASIC stores the numbers 
1.000001 and 1.000000 (seven digits) differently but stores 1.0000001 
and 1.0000000 (eight digits) as the same number. Double precision 
arithmetic allows you to specify floating point numbers to 15 digits 
of precision. 

If you need more than seven digits of precision, you should use BASIC 
with double precision arithmetic. However, double precision BASIC has 
two disadvantages. 

1. It allows less BASIC program space, because BASIC itself 
requires more memory and because all floating point 
constants, variables, and arrays require twice the memory 
that single precision would need. 

2. Arithmetic operations and functions run more slowly with 
double precision than with single precision. 

The PRINT statement only prints six digits even when you are using 
double precision arithmetic. Consequently, if you want to print a 
number with more than six digits, you must use the PRINT USING 
statement or the STR$ function. The following example was run using 
double precision arithmetic. 

LISTNH 

10 X=4, 237 194237 

20 Y=6. 9090909 

30 P'RINT X*Y 

40 PR I NT US I NG " #* . ******* " » X* Y 

50 PRINT STR*(X*Y) 

READY 
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RI.INNH 

29.2752 
29*275:1.601 
29.275:1.60:144389 

READY 

Double precision compiled BASIC uses the default file type .BAX while 
single precision compiled BASIC programs have the default file type 
.BAG. The different default file types are necessary because double 
precision BASIC cannot read a program compiled by single precision 
BASIC and vice versa. If you are using double precision BASIC and 
specify the file type of a program compiled by single precision BASIC 
or vice versa, the results are unpredictable. 



1.6 SYSTEM DEPENDENT ERROR MESSAGES 



Some of the error messages listed in the BASIC-11 Language Reference 
Manual either have special meaning in BASIC-ll/RT-11 or are not 
produced by it. These error messages are 

PCANNOT DELETE FILE (?CDF) 

BASIC-ll/RT-11 does not produce this message. 

7ERR0R CLOSING CHANNEL (?ECC) 

BASIC-ll/RT-11 does not produce this error message. If an error 
occurs when BASIC-ll/RT-11 is trying to close a channel, 
BASIC-ll/RT-11 prints the 7CHANNEL I/O ERROR (?CIE). 

?FILE ALREADY EXISTS (?FAE) 

BASIC-ll/RT-11 does not produce this message. 

?FILE PRIVILEGE VIOLATION (?FPV) 

BASIC-ll/RT-11 does not produce this message. 



If the error occurs 
If the error occurs 



7FILE TOO SHORT {?FTS) 

The file is too small to contain the output 

in a data file, specify a larger FILESIZE 

in a program file, delete unused files with the UNSAVE command 

and then retry. 

7ILLEGAL DEF (7IDF) 

BAISC-ll/RT-11 does not produce this message. 

7 ILLEGAL FILE LENGTH 

The FILESIZE specified was less than -1 (see Section 2.2). 

7ILLEGAL RECORD SIZE (7IRS) 

BASIC-ll/RT-11 does not produce this message. 

7N0T A VALID DEVICE (7NVD) 

BASIC-ll/RT-11 does not produce this message. 



7N0T ENOUGH ROOM (7NER) 

There is not enough room for the FILESIZE specified, 
unused files with the UNSAVE command. 



Delete 
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FILES 

2.1 FILE SPECIFICATION 

BASIC uses the standard RT-11 file specification. Its format is: 

[device :1 [filename] [. typej 

where: 

device is the device name. It can be any device name 
listed in Table 2-1 or any assigned device name (see 
the RT-11 User's Guide). 

filename is the one- to six-character name of the file. 

type is the zero- to three-character type of the file. 



Table 2-1 
RT.-ll Device Names 



Code 


Device 


CR: 


Card Reader 




CTn: 


Cassette 




DLn: 


RLOl Disk 




DMn: 


RK06 Disk 




DPn: 


RP02 Disk 




DSn: 


RJS03/4 Disk 




DTn: 


DECtape 




DXn: 


RXll Diskette 




LP: 


Line Printer 




MMn: 


TJU16 Magtape 




MTn: 


TMll Magtape 




PC: 


Combined high-speed paper tape 


reader and punch 


RF: 


RFll Disk 





(continued on next page) 
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Table 2-1 (Cont. ) 
RT-11 Device Names 



Code 



RKn: 

TT: 

SYn: 

DK: 



Device 



RK05 Disk 

Console Terminal Keyboard/Printer 

System device (the volume from which the 
monitor was bootstrapped) 

The default storage volume 



If you do not specify any of the elements of the file specification, 
BASIC uses a default value. 

The default device is DK:. The default for the file name and file 
type depends on the statement or command in which the file specifica- 
tion appears. Table 2-2 shows the file name defaults, and Table 2-3 
shows the file type defaults. 



Table 2-2 
Default File Names 



Statement or Command 


Default 


SAVE, REPLACE, COMPILE 

OLD, APPEND, CHAIN 
OVERLAY 

UNSAVE, OPEN, KILL 
NAME 


the current program name 
the file name NONAME 

no default but prints 
the 7ILLEGAL FILE 
SPECIFICATION (?IFS) 
error message instead. 



Table 2-3 
Default File Types 



Statement or Command 


Single precision 
BASIC Default 


Double precision 
BASIC Default 


OPEN, KILL, NAME 


.DAT 


.DAT 


SAVE , REPLACE , UNSAVE 
APPEND 


.BAS 


.BAS 


COMPILE 


.BAC 


.BAX 


RUN, OLD 


.BAC (and if a .BAC 
cannot be found .BAS) 


.BAX (and if a 
.BAX cannot be 
found .BAS) 
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When you create a file whose file specification is the sam^ as an 
existing file, the older file will be deleted (superseded) when the 
new file is closed. you can avoid unwanted deletions by using the 
SAVE command to save new files. If a SAVE command specifies a file 
name that already exists, BASIC-11 prints the following error message: 

?USE REPLACE (TRPL) 

This gives you an opportunity to decide whether you want to supersede 
the old file, or store the file under a different file specification. 



2.2 THE OPEN STATEMENT - SYSTEM DEPENDENT FEATURES 
The format of the OPEN statement is: 

RFOR INPUT')"] 
FOR OUTPUT fj AS FILE [#] exprl [DOUBLE BUF] 



[,RECORDSIZE expr2] [,MODE exprS] [,FILESIZE expr4] 



where: 



string 
exprl 
DOUBLE BUF 

RECORDSIZE expr2 
MODE expr3 
FILESIZE expr4 



is a file specification as described 
Section 2.1. 



m 



is the channel number of the file, 
have any value between 1 and 12. 



It can 



causes the file to be double buffered. 
Double buffering increases the speed of some 
file operations but requires additional 
memory for the second buffer. 

is ignored if specified. 



is ignored if specified, 



if posit 
256-word 
FILESIZE 
requests 
allocati 
free ar 
area, wh 
-1, it 
area. I 
message 



ive, specifies 
blocks the 

is missing or 

the standar 

on (that is, e 

ea or all of 

ichever is lar 

requests the 
f expr4 is les 
? ILLEGAL FILE 



the maximum number of 

file can occupy. If 

expr4 equals 0, it 

d BASIC-ll/RT-11 file 

ither half the largest 

the second-largest free 

ger). If expr4 equals 

absolute largest free 

s than -1, the error 

LENGTH appears. 



The elements of the OPEN statement described above are the system 
dependent elements. The other elements of the OPEN statement are 
described in the BASIC-11 Language Reference Manual. 



2.3 LISTING YOUR FILE DIRECTORY 

You must return control to the RT-11 monitor before listing your file 
directory. First save your current BASIC program (if you wish to 
reuse it later) and then enter the BYE command. The monitor prints 
the dot prompt. For example: 
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SAME TEHP 

READY 
BYE 

Following the prompt, type the RT-11 DIRECTORY command. A simplified 
format of the RT-11 directory command (see the RT-11 System User's 
Guide for a complete description) is: 

PTRECTORY [/F'RINTEr] file specification 

where: 

/PRINTER specifies that the directory is to be 

printed on the line printer. (If 
omitted, the directory is printed on the 
terminal. ) 

file specification specifies the files that you want 

listed. If you omit the file 
specification, all files are listed. 

The DIRECTORY command wildcard feature allows you to specify files 
with similar file names, or similar file types, or both. If you 
substitute an asterisk for the file name but specify a file type, all 
files with that file type are listed. For example, the following 
command lists all BASIC source programs on the line printer: 

« DIRECTORY/PRINTER * , BAS 

Similarly, if you substitute an asterisk for the file type, but 

specify a file name, all files with that file name are listed, 

regardless of file type. For example, the following command lists all 
files with the file name TEST: 

♦ JCi I R E C T R Y / P R 1 N J E R T li;: S T . >K 

If you specify a percent sign in place of any characters in a file 
name or file type (for example, TEST%%.BAS), then all the files whose 
specifiers match the other characters in the specification are listed 
(TESTAE. BAS, TESTOl.BAS, and TESTER. BAS would be listed, if they 
exist, for the specification TEST%%.BAS). 

To list all the BASIC programs and compiled BASIC programs, type: 

♦DIRECTORY >K.BA% 

Note that this command also lists files with the file type .BAK and 
.BAT. Because the specification /PRINTER is absent, listing occurs on 
the terminal. 

After listing your directory, you can return to BASIC by using the 
BASIC command, then restore your saved program with the OLD command, 
and finally, delete the temporary file. For example: 

♦ EiASIC 
BASIC-ll/RT-:l.l V02-XX 

OPTIONAL. FUNCTIONS (ALLi- NONE.- OR INDIVIDUAL)? A 

READY 
OLD TEMP 

READY 
UNSAVE TEMP 

READY 
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CHAPTER 3 
UTILITY FUNCTIONS 

3.1 BASIC UTILITY FUNCTIONS 
BASIC has utility functions to: 

• Change the terminal width (TTYSET) 

• Cancel the effect of CTRL/0 (RCTRLO) 

• Disable CTRL/C (CTRLC and RCTRLC) 

• Terminate your program (ABORT) 

• Input a single character from your terminal (SYS) 

• Terminate BASIC (SYS) 

• Check if a CTRL/C has been typed (SYS) 

• Enable lower case support (SYS) 

In the following sections, BASIC-11 utility functions are shown in the 
context of a LET statement with a dummy target variable, as follows: 

[letJ variable = utility function 

where: 

variable is the target variable. 

utility function is one of the functions described in this 

chapter. 

Actually, utility functions can appear in any arithmetic expression. 
The LET statement format is recommended because it is the simplest 
statement, and consequently, produces easier-to-read programs. 

3.2 SETTING THE TERMINAL MARGIN (TTYSET FUNCTION) 

Use the TTYSET function to set your terminal's right margin. BASIC 
prints on a line until a number or string would extend past the margin 
you set. BASIC then prints a return and line feed on the current line 
and prints the string or number on the next line. 

The format of the TTYSET function is: 

[let] variable=TTYSET( 255%, expression) 
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where: 

variable is the target variable and contains an undefined 
value after the statement is executed. 

255% is either a numeric constant (as specified in 

format) or an expression with an integer value of 

255 (for compatibility with other versions of 
BASIC) . 

expression specifies the right margin of the terminal. The 
margin is set to the value of the expression minus 
1. If the expression equals 0, BASIC does not 
change the previous margin. 

For example, to set BASIC to print to the full width of an IiA36 
DECwriter II (132 columns), type: 

A=TTYSET ( 255% j 133% ) 

To set BASIC to print to the full width of a VT50 display terminal (80 
columns) , type: 

A=TTYSET(225%!.8:1%) 

If you do not specify the TTYSET function, BASIC assumes a terminal 
with 72 columns. 

Ensure that the system's margin for your terminal is equal to or 
greater than the margin you specify in TTYSET. 

If the value of the expression is less than 0, equal to 1, or greater 
than 256, BASIC prints the 7ARGUMENT ERROR (?ARG) message. If the 
first argument has a value other than 255, BASIC prints the same 
message. 



3.3 CANCELING THE EFFECT OF CTRL/0 (RCTRLO FUNCTION) 

BASIC Stops terminal output when the CTRL/O key is typed; however, 
the RCTRLO function causes BASIC to resume printing. Use the RCTRLO 
function to ensure that certain data is printed on the terminal even 
if a CTRL/0 has been typed. 

The format of the function is: 

[let] variable=RCTRLO 

where: 

variable is the target variable and contains an undefined 
value after the statement is executed. 



Consider the following example: 



3-2 



UTILITY FUNCTIONS 



LISTNH 

10 REH PROGKAM TO INPUT DATA 

20 REM FROM FILE AND PRINT SUM 

30 OPEN "NUMBR" FOR INPUT AS FILE *1 

40 PRINT 'DATA IN FILE?" 

50 IF END *1 THEN 100 

60 INPUT *1»D 

70 PRINT D 

80 T=TfD 

90 GO TO 50 

100 A==:RCTRLO 

110 PRINT 

120 PRINT "SUM'^^'ST 

READY 
RUNNH 

4 

16 
147 
26 



CCTRL/O) 

SUM--= 4172 

READY 

While BASIC executes the loop from line 50 to line 90 it prints out 
numbers. If CTRL/0 is typed BASIC stops printing. But when BASIC 
executes line 100, BASIC resumes printing. 



3.4 DISABLING CTRL/C (RCTRLC AND CTRLC FUNCTIONS) 

In certain parts of the program you may need to override CTRL/C 
interrupts from the terminal. The RCTRLC function disables CTRL/C and 
prevents it from stopping the BASIC program. The CTRLC function 
enables the CTRL/C key command. 

The format of the functions are: 

[let] variable=RCTRLC 

[let] variable=CTRLC 
where: 

variable is the target variable; it contains an undefined 
value after the statement is executed. 

After BASIC executes the RCTRLC function, typing CTRL/C on the 
terminal does not stop the program. 

After BASIC executes the CTRLC function, typing CTRL/C stops the 
program. BASIC does not save any CTRL/C that is typed while CTRL/C is 
disabled. If the program encounters a CTRL/C function, and no prior 
RCTRLC function is in effect, the CTRL/C function has no effect. 

When BASIC prints the READY message, it automatically enables the 
CTRL/C key command. 

For example: 
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LISTNH 

1000 REM DO NOT ALLOW INTERRUPTS 

1010 A^RCTRLC 

1020 PRINT "NO INTERRUPTS" . 

1030 FOR 1=^ 1 TO 1000 \ S^==S+I \ NEXT I 

1100 REM NOW ALLOW INTERRUPTS 

1110 A~:CTRLC 

1120 PRINT "INTERRUPTS OKAY" 

1130 FOR I ^■■■■- 1 TO 1000 \ S^^S+I \ NEXT I 

32767 ENIi 

READY 
RUNNH 

NO INTERRUPTS 



CCTRL/C) 

INTERRUPTS OKAY 

(CTRL/C) 

STOP AT LINE 1130 
READY 

For information on a system function that determines if CTRL/C has 
been typed while CTRL/C is disabled, see Section 3.6.3. 

NOTE 

Once CTRL/C is disabled it is not 
possible to interrupt BASIC. Do not 
disable CTRL/C until your program is 
debugged. 



3.5 TERMINATING YOUR PROGRAM (ABORT FUNCTION) 

If you want a program to delete itself from memory when it terminates, 
use the ABORT function. The ABORT function is equivalent to an END 
statement except that ABORT can optionally delete your program from 
memory and change the program name to NONAME (equivalent to the SCR 
command) . 

The format of the ABORT function is: 

[let] variable=ABORT (expression) 

where: 

variable is the target variable; it contains an undefined 
value after the statement is executed. 

expression determines if the program is to be deleted from 
memory. If expression equals 0, BASIC does not 
delete the program. If expression equals 1, BASIC 
deletes the program. 

Consider the following examples: 
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Delete from memory 
when program completed 

LIST 

ABORT 2:l.-JUN-77 :l4t52MS 

10 PRINT "123" 
20 A-:-ABORT<l) 
30 PRINT "456" 

READY 
RUNNH 

123 

READY 
LIST 

NONAME 2 1 -• Jl.JN-76 1 4 : 53 } 30 



Do not delete when 
program completed 



LIST 
ABORT 



21-JUN-77 14:54:00 



READY 



10 PRINT "123" 
20 A:=ABORT<0) 
30 PRINT "456" 

READY 

RUNNH 

123 

READY 
LIST 

ABORT 21-JUN-76 14 : 54 t 30 

10 PRINT "123" 
20 A'=ABORT(0) 
30 PRINT "456" 



READY 

3.6 SYSTEM FUNCTIONS 

System functions perform system-dependent operations. 

The formats of the system functions are: 

[letJ variable= SYS (expressionl ,expression2 ) 
where: 

is the target variable. 

determines the function to be performed. 



variable 

expressionl 

expression2 



is an optional argument used in some system 
functions. 



Table 3-1 summarizes the functions performed according to the 
specified value of expressionl. Any value of expressionl other than 
those specified causes BASIC to print the 7ARGUMENT ERROR (?ARG) 
message. 
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Table 3-1 
Summary of System Functions 



Value of 
expressionl 



Function Performed 



Processes input one character at a time. Target 
variable contains the ASCII value of the next 
character typed at the terminal. 

Terminates BASIC and returns control to system 
monitor (equivalent to the BYE command). 

Determines if CTRL/C has been typed while CTRL/C is 
disabled by RCTRLC function. Target variable equals 
1 if CTRL/C has been typed and equals if CTRL/C has 
not been typed. 

Enables or disables lower case input from your 
terminal. If expression2 equals 0, lower case 
character input is allowed. If expression2 equals 1, 
lower case character input is converted to the 
equivalent upper case character input. 



3.6.1 Single Character Input 

Use the single character input system function, 
input one character at a time. 



SYS(l), to process 



SYS(l) returns the seven-bit ASCII value of any character typed on the 
terminal except CTRL/C. (See the BASIC-11 Language Reference Manual 
for a list of the ASCII values.) If CTRL/C is typed when BASIC is 
executing SYS(l) and CTRL/C is enabled, then BASIC prints the STOP and 
READY messages. If CTRL/C is disabled, then BASIC continues executing 
SYS(l) and waits for another character. BASIC cannot process the 
character until you type the RETURN key. 

LISTNH 

:l.0 PRINT "TYPE A CHARACTER? "J 

20 A==SYS(1) 

40 PRINT "THE ASCII VALUE 0^• "yCHR$(A)v" IS" PA 



READY 

RUNNH 

TYPE A CHARACTER t Z 

THE ASCII VALUE OF Z IS 90 

READY 



3.6.2 Terminating BASIC 

To terminate BASIC from a BASIC program, use system function SYS (4) 
It is equivalent in effect to the BYE Command. 

For example: 
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LISTNH 

10 PRINT "GOODBYE- 

20 A:='SYS<4) 

READY 
FI:UNNH 
GOODBYE 



3.6.3 Checking for CTRL/C 



If you have disabled CTRL/C with the RCTRLC function and want to check 
if CTRL/C has been typed, use system function SYS (6). The function 
returns a 1 if CTRL/C has been typed and a if it has not been typed. 

For example: 

LISTNH 

10 A--RCTRLC \ REM Disable CTRL/C. 

30 B'«SYS<A) \ REM Check for CTRL/C. 

40 IF B™1 THEN 100 

50 PRINT "STILL EXECUTING" 

60 (30 TO 30 

100 PRINT "PROGRAM TERMINATING" 

110 A--»CTRLC REM Ro^nable CTRL/C, 

120 A™AB0RT<1) 

READY 

RUNNH 

STILL EXECUTING 
STILL EXEC UTING 

(CTRL/O CCTRL/a 

STILL EXECUTING 
PROGRAM TERMINATING 

READY 



3.6.4 Enabling Lower Case Support 

If you want to enter lower case characters at your terminal/ use the 
system function SYS (7,expr2) . The RT-ll system usually converts all 
lower case alphabetic characters to upper case. Executing the 
function SYS (7,0) causes RT-ll to stop converting lower case 
characters and to pass them unchanged. To cause RT-ll to resume 
converting lower case characters, you must execute the function 
SYS(7,1). After you exit from BASIC, the monitor continues to process 
characters as it did before BASIC was active. 

The following example demonstrates how to enable and disable lower 
case. The program is first run to enable lower case by causing the 
function SYS{7%,0%) to be executed. After this the program is 
modified to allow the user to enter a lower case response. Finally, 
the modified form of the program is run; this disables lower case. 
The modified program is then saved. 
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LIBTNH 

:10 REM PROGRAM TO CHANGE LOWER CASE CONVERSION 

20 PRINT "DO YOU WANT TO ENTER LOWER CASE CHARACTERS (Y OR N)"? 

30 INPUT A* 

40 IF A*:=-"Y" THEN 100 

50 IF A$<>"N" THEN 20 

60 fif~-SYB(77.,17:) \ REM DISABLE LOWER CASE 

70 GO TO 32767 

.1.00 A=^SYS(7%i.0%) \ REM ENABLE LOWER CASE 

32767 END 

READY 
RIJNNH 

DO YOU WANT TO ENTER LOWER CASE CHARACTERS (Y OR N)? Y 

READY 

4l'i i. r <^ *■•-"«" bheii :l.00 \ rem Check for lower case w 

sub 50 (?20@.Lr a*::>"ii" then 20 \ Rem Check for lower c<3S»e n 

50 IF A*<>"N" THEN IT 3$<>"n" then 20 \ Rem Check for lower C3se n 

READY 

:i .ii.tiih 

10 REM PROGRAM TO CHANGE LOWER CASE CONVERSION 

20 PRINT "DO YOU WANT TO ENTER LOWER CASE CHARACTERS (Y OR N)"» 

30 INPUT A* 

40 IF A*---"Y" THEN 100 

45 IF A*~-"y" THEN 100 \ REM Check for lower case y 

50 IF A$<>"N" THEN IF A*<:>"n" THEN 20 \ REM Check for lower case n 

60 fi>='SyS(7Z>17.) \ REM DISABLE LOWER CASE 

70 GO TO 32767 

100 A=SYS(7/i:»07.) \ REM ENABLE LOWER CASE 

32767 END 

READY 

runnh 

DO YOU WANT TO ENTER LOWER CASE CHARACTERS (Y OR N)? n 

READY 

SAVE LOWCHM 

READY 

If you type lower case letters when lower case is disabled, they are 
echoed as upper case. 

Note that BASIC converts lower case keywords and variable names to 
upper case characters but leaves string constants, strings entered at 
the terminal, and remarks unchanged. 
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CHAPTER 4 
USING ASSEMBLY LANGUAGE ROUTINES WITH BASIC 

4.1 INTRODUCTION TO ASSEMBLY LANGUAGE ROUTINES 

BASIC-11 allows you to add assembly language routines (ALRs) to expand 
or extend BASIC'S capabilities. For example, you can write routines 
for communication with special devices (such as laboratory equipment) 
or to manipulate arrays. Once added to BASIC, such routines can be 
executed in immediate mode or in programs, by means of the CALL 
statement. (See the BASIC-11 Language Reference Manual.) applications 
programs. There are several advantages to doing this rather than 
doing all your programming in assembly language. They are: 

• Only the programmer writing the routine need know assembly 
language. The application programmers need only to know 
BASIC. 

• It is easier to write, debug, and modify BASIC programs than 
assembly language programs. You can write, execute, debug, 
and modify your program without leavi^ig BASIC. 

• You can execute ALRs without writing a program, using 
immediate mode CALL statements. 

NOTE 

This chapter assumes that you are an 
experienced MACRO-11 programmer and that 
you are familiar with your operating 
system and its utility programs 
(editors, MACRO assemblers, task 
builders, linkers, etc.) 

This chapter describes: 

• ALR format. 

• The procedure to access arguments. 

• Use of auxiliary routines provided by BASIC. 

See the BASIC-ll/RT-11 Installation Guide for the procedure to add the 
routines to BASIC. 

ALRs that use the FORTRAN IV call interface (as defined in RT-11 
FORTRAN IV User's Guide ) can be called from either FORTRAN IV or RT-11 
BASIC. However, these ALRs must not access any routines or global 
locations in FORTRAN IV itself. 
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4.2 FORMAT OF THE ASSEMBLY LANGUAGE ROUTINE 

To write an assembly language routine (ALR) that you can add to BASIC, 
you first must specify the name of the routine and its starting 
address in the user routine Name Table (see Figure 4-1) . You must 
include a pointer for each ALR after the global location FTBL. Each 
pointer specifies the location of the routine name and starting 
address. A word containing all O's terminates the pointer list. 



NOTE 

ALR names must not contain embedded 
blanks. For compatibility with FORTRAN, 
routine names longer than six ASCII 
characters should be avoided (although 
BASIC imposes no length restriction 
other than the limit of the program line 
size) . 



Routine Name 



User Routine Name Table 



1st character 
of routine name 



3rd character 
of routine name 



Number of characters 
in routine name 



2nd character of 
routine name 



if needed 



Last character of 
routine name 



Pointer to starting address of routine 



Pointer to 1st routine name 



Pointer to 2nd routine name 



Pointer to 3rd routine name 



FTBL 




Pointer to last routine name 



Figure 4-1 User Routine Name Table and Routine Name Formats 

The BASIC software kit includes a file BSCLI.MAC, with global location 
FTBL. This file is the basis of the pointer table. You build the 
pointer table by adding entries between global location FTBL and the 
.WORD entry, using the system editor. 

Normally, placing the ALR's routine name at the beginning of the 
routine is recommended- In this case the pointers in the user routine 
name table should be globals. For example, if you have written three 
routines named INITIT, ADDER, and CHKSTA, the routine name list should 
be: 





.GLOBL 


FTABI 






TABU 
TBI.. J 


. GLOBL 

.WORD 

.WORD 


INITNMv 

FTBL 

INITNM 


ADDNM i. 
5 USER 


CHKSNM 
ROUTINE 




. WORD 


ADDNM 


iSNAME 


LIST 




.WORD 
.WORD 


CHKSNM 








.END 
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NOTE 

You Should edit the items printed in red 
in this listing into the file BSCLI.MAC. 
The items printed in black are already 
in the file. 



The locations, INITNM, ADDNM, and CHKNM should be at the beginning of 
the INITIT, ADDER, and CHCKST, respectively. For example: 

i THE INIT ROUTINE 

♦GLOBL INITNH 
INITNMS .BYTE 6 J NUMBER OF CHARACTERS IN NAME 
.ASCII "INITIT" 
. EVEN 

.word initst 
:i:nitstj sstart of routine 



An alternative method is to add the routine name and starting address 

after the routine name table. In this case the starting addresses of 

the routines should be globals. Using the same examples as above, the 
routine name table should be: 





.GLOBL 


FTABI 




. GLOBL 


INITST > ADDBT. CHKSST 


FTABi: 


.WORD 


FTBL 


ftbl: 


. WORD 


INITNM 




, WORD 


ADDNM 




. WORD 


CHKSNM 




. WORD 





INITNM t 


.BYTE 


6 ; NUMBER OF CHARACTERS IN NAME 




.ASCII 


"INITIT" 




.EVEN 






.WORD 


INITST 


ADDNM 


.BYTE 


5 




.ASCII 


"ADDER" 




.EUEN 






.WORD 


ADDST 


CHKSNMt 


.BYTE 


6 




.ASCII 


"CHKSTA" 




. EVEN 






.WORD 


CHKSST 



.END 



Each ALR should start with the global address specified. For example: 



INITSTJ 



THE INITIT ROUTINE 
.GLOBL INITST 

J START OF ROUTINE 



You should use this alternative method when you are adding an ALR 
written for FORTRAN IV to BASIC. 
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All the examples in this chapter use the recommended method (where the 
routine name packet is at the start of the routine) . 

Once you have defined the name and starting address of the routine, 
you can write the routine itself. The ALR can use the stack but it 
must ensure that the stack limit is not exceeded. BASIC puts the 
stack limit in R4 before transferring control to the ALR. If you use 
any of the mathematical operations or function routines provided by 
BASIC, ensure that there is enough free space on the stack before 
executing the routine (15 free words for single precision routines and 
30 free words for double precision routines). The ALR must end with 
an RTS PC instruction with the stack unchanged from its original 
state. The format of the INITIT routine is: 

i THE INIT ROUTINE 





.(3L0BL 


INITNM 




initnm: 


BYTE 


6 






.ASCII 


"INITIT" 






*EVEN 








.WORD 


INITST 




INITSTJ 




» START OF" 


ROUTINIi 



MAIN BODY OF ROUTINE 



RTS PC SEND OF ROUTINE 



4.3 ACCESSING THE ARGUMENTS - THE ARGUMENT LISTS 

When BASIC executes the CALL statement, it evaluates the arguments and 
provides the routine with two lists. One contains pointers to the 
evaluated arguments and the other contains descriptors of the argument 
types. An assembly language routine (ALR) should ensure that the list 
contains the expected number and the right type of arguments. 

Argument checking ensures that errors in a BASIC program will not 
cause a fatal error in the ALR or in BASIC itself. If no argument 
checking is done and a CALL statement contains an incorrect data type, 
the ALR produces unpredictable results. For example, if the ALR 
expects an integer array and the CALL statement contains a string 
expression, the ALR could overwrite sections of the stack. If the ALR 
checks arguments for errors, it can protect itself from errors in 
BASIC programs. (There is no protection from errors in the ALR 
itself. ) 

A FORTRAN-compatible ALR cannot check arguments unless it first checks 
and determines that the language calling it is BASIC, because FORTRAN 
does not provide an argument descriptor list. 

Before BASIC transfers control to the ALR, it evaluates the arguments 
in the CALL statement. It creates a list of pointers to the arguments 
and a list of argument descriptors. Figure 4-2 shows the argument 
descriptor lists that BASIC creates before it transfers control to the 
ALR. 
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Argument Descriptor List 



Descriptor of 1st argument 



Descriptor of 2nd argument 



Descriptor of last argument 



Pointer to descriptor List 



ID Byte 



Number of Arguments 



Potnter to 1st argument 



Pointer to 2nd argument 



Pointer to List 



Pointer to last argument 



Argument 

Pointer 

List 



Figure 4-2 Assembly Language Routine Argument Lists 

As shown in Figure 4-2, R5 points to a word that specifies the number 
of arguments in the CALL statement and identifies the language calling 
the ALR. The argument pointer list starts at the next word and the 
pointer to the argument descriptor list is stored in the previous 
word. 



Each byte of the word pointed to by R5 is meaningful. The low-order 
byte contains the number of arguments. The high order byte identifies 
the language. If the calling language is BASIC, the high order byte 
has a value of 202. If the calling language is FORTRAN IV, the 
high -order byte has a value of 0. 

The pointers in the argument pointer list specify the location of the 
evaluated arguments. There are two exceptions, pointers for null 
arguments and pointers for string array arguments. 

If an argument is null then its pointer does not point to that 
argument but instead contains a value of -1. A CALL statement 
argument list with two adjacent commas or a terminating command 
produces a null argument. For example, CALL "INITIT" (A, B, , D,) 
produces the following arguments: A, B, null, D, and null. 

If the argument is a string array, then the pointer does not point to 
that argument but instead contains a value needed to access the string 
array. (See Section 4.3.2.) If the argument is an unsubscripted 
string or an element of a string array, the pointer specifies the 
location of the first character of the string. 

The argument descriptor list specifies the data type of each argument. 
It also indicates whether the argument is an array or not and whether 
the ALR can return a result in the argument. 



BASIC provide 
these cases 
the descripto 
Figure 4-3 
indicates if 
the value o 
descriptor li 
the descript 
word for stri 



s additional information for strings and arrays. In 
the word in the argument descriptor list is a pointer to 
r word, which has the additional information after it. 
describes the format of the descriptor word. BASIC 
a word in the list is a pointer or a descriptor word by 
f the bit. If the bit is clear, then the word in the 
st is a pointer. If the bit is set, then the word in 
or list is the descriptor word. Note that the descriptor 
ngs and arrays has a value of in the bit. 



NOTE 

All numbers in this chapter that specify 
the contents of a word or a section of a 
word are octal numbers not decimal 
numbers. 
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Figure 4-3 Format of the Argument Descriptor Word 



The ALR can return arguments only to variables and arrays. If the 
argument is an expression, constant, or element of a virtual array, 
the seventh bit of the argument descriptor word is set and the ALR 
must not return a value to that argument. 

Bits 12 through 8 of the argument descriptor word specify the size of 
the data type. The ALR does not need to check this information 
because each argument type (specified in bits 6 through 1) has a fixed 
size. The contents of bits 12 through 8 for a string argument can be 
ignored. 
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cription of these routines. 

and string descriptors. 
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Descriptor word for numeric scalar 
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Pointer to array descriptor 
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Pointer to string scalar descriptor 



Descriptor word for numeric scalar 



Figure 4-4 Format of Array and String Argument Descriptors 



4.3.1 Numeric Arrays 

If the CALL statement specifies an element of a numeric array, for 
example A (10), BASIC considers it a 1-dimensional array starting with 
the specified element and ending with the last element of the array. 
BASIC considers it a one-dimensional array even if the entire array is 
two-dimensional. 

BASIC and FORTRAN IV store arrays differently. BASIC array subscripts 
start at 0, but FORTRAN array subscripts start at 1. In BASIC arrays, 
the second subscript varies faster, but in FORTRAN IV arrays the first 
subscript varies faster. If you are designing a routine to be called 
from either BASIC or FORTRAN IV, you must consider these differences 
in the ALR. 



4.3.2 Strings and String Arrays 

This section describes the routines BASIC provides to allow the 
assembly language routine (ALR) to access strings. It also describes 
some example routines which use these string access routines. BASIC 
allows dynamic-length strings, whose length can change during program 
execution. The BASIC string access routines keep track of the 
location and size of strings. Consequently, an ALR cannot change a 
BASIC string without using the string access routines. 

The procedures for accessing strings and for accessing elements of 
string arrays are different. Note that if the CALL statement 
specifies an element of a string array (for example, A$(10)), BASIC 
considers it a string scalar. Only if the entire array is passed (for 
example, A$()), does BASIC consider it a string array. 
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The ALR must locate and retrieve the string reference pointer word and 
pass it to the string access routines. For a string argument, the 
string reference pointer is the word following the descriptor word. 
For a string array argument, The ALR must calculate the string 
reference pointer to access any element of the array. The string 
reference pointer is a word whose value is determined by the following 
formula: 

string reference pointer=2*of f set+argument pointer 

where: offset ' is the position of the element in the 

array. 

argument pointer is the value for the string array in the 

list of argument pointers. (Note the 
argument pointer for a string array does 
not point to the argument itself.) 

The offset for an element of a one-dimensional array is equal to the 
value of its subscript. The offset for an element of a 
two-dimensional array is defined by this formula: 

of fset=subscriptl* {maximum value of subscript2+l) +subscr ipt2 

For example, consider two arrays A? (10) and B$(3,5) with argument 
pointers of A and B respectively. (NOTE: All numbers in the 
following list are decimal.) 

Element 2*offset+argument pointer string reference pointer 

A$(0) 2*0+A A 

A$(4) 2*4+A 8+A 

B$(0,5) 2*(0*6+5)+B 10+B 

B$(l,5) 2*(l*6+5)+B 22+B 

B$(2,0) 2*(2*6+0)+B 24+B 

The string access routines use the string reference pointer that the 
ALR provides to find and manipulate the string. 

BASIC provides four string access routines: 

$FIND 
$ALC 
$STORE 
$DEALC 

The $FIND routine returns the length of a string and a pointer to the 
first character. The $ALC routine allocates a temporary string. An 
ALR can only write characters directly to strings created by $ALC. 
The $STORE routine assigns the value of one string to a second string 
and changes the first string to a null string. The $DEALC routine 
deallocates space used by the temporary string on the stack. 

The ALR should use the following general procedure to manipulate a 
string argument and then return the resultant string. First, the ALR 
accesses the string argument by using the $FIND routine. Then it 
creates a temporary string with the $ALC routine. It then reads the 
characters of the string argument, manipulates them in the desired 
way, and writes the characters out to the temporary string. After 
this the ALR uses the $STORE routine to copy the temporary string to a 
string argument (which can be the original string). Finally, it uses 
the $DEALC routine to remove data placed on the stack by the $ALC 
routine. 
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Table 4-1, "Usin^ String Access Routines", describes the four string 
access routines. It describes the initial setup, including the format 
of the subroutine jump (JSR) instruction required to invoke the string 
access routine. It also describes the expected results and how to 
interpret them. (In particular, it indicates how to determine whether 
or not you made a correct initial setup in preparation for the string 
access routine.) 

If the ALR calls $FIND, $ALC, $STORE, and $DEALC, it must specify them 
as global locations. 

Before calling any of these routines, you must ensure that R5 contains 
its initial value, the value it had when BASIC transferred control to 
the ALR. That is, R5 must point to the word identifying BASIC and 
specifying the number of arguments. 

NOTE 

These routines require that a register 
contain the same value in bits 6-1 as an 
argument descriptor word for a string 
argument. You can ensure this by moving 
a value of 100 into the specified 
register {puts a value of 40 in bits 
6-1) or by moving an argument descriptor 
word in the specifed register. 



4.4 USING ROUTINES PROVIDED BY BASIC 

BASIC provides routines that handle error conditions, print messages 
on the terminal and perform mathematical operations and functions. 



4.4.1 Error Handling and Message Routines 

BASIC provides two error handling routines ($ARGER and $BOMB) and two 
message printing routines ($MSG and $CHROT) . The $ARGER routine 
produces the fatal 7ARGUMENT ERROR (?ARG) message. The ALR should 
call $ARGER when it detects an incorrect argument. The $BOMB routine 
allows the ALR to specify its own fatal message. The $MSG routine 
prints any message on the terminal and then returns control to the 
ALR. The $CHROT routine prints any single character on the terminal 
and then returns control to the ALR. 

If the ALR calls $ARGER, $BOMB, $MSG, or $CHROT, it must specify them 
as global locations. 

Call the $ARGER routine by executing the instruction: 

JMP *ARGEF^ 

The $ARGER routine prints the error message on the terminal in one of 
the following formats: 

TARGUMENT ERROR AT LINE xxxxx 
?ARG AT LINE xxxxx 

where: 

xxxxx is the line number of the CALL statement. 
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If the CALL statement was an immediate mode statement, then AT LINE 
xxxxx is not printed. Control then returns to BASIC, which prints the 
READY message. 

Call the $BOMB routine by executing the following instruction: 

JSf! R1»$B0MB 
.ASCIZ 'message' 
.EVEN 

where: 

message is the string of characters that you wish to print. 

The $BOMB routine prints the error message on the terminal in the 
form: 

Terror message AT LINE xxxxx 

where: 

xxxxx is the line number of the CALL statement. 

If the CALL statement was an immediate mode statement, then AT LINE 
xxxxx is not printed. Control then returns to BASIC, which prints the 
READY message. 

Call the $MSG routine by executing the instruction: 

JSR Rlf«HS{3 

♦ASCII 'message' 

.BYTE 15»:L2!.0 yMUST HAVE CARRIAGE RETURN 

.EVEN 5 AND LINE FEED AND END WITH 

where: 

message is the string of characters that you wish to print. 

The $MSG routine prints the message you specify on the terminal, and 
then returns control to the instruction that follows the .EVEN 
instruction. 

Call the $CHROT routine as follows: 

1. put the 8-bit ASCII code of the character in the low order 
byte of RO 

2. execute the instruction: 

JSR PC).$CHROT 

$CHROT prints the character specified in RO on the terminal, and then 
returns control to the ALR. 



4.4.2 Mathematical Operation and Function Routines 

Assembly language routines (ALRs) can use BASIC'S mathematical 
operation and function routine to perform operations and functions 
that you can use in a BASIC program. ALRs can use the same routine 
that BASIC itself uses to perform these operations and functions. An 
advantage of this is that the ALR need not duplicate routines that 
already exist in BASIC. 
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NOTE 

Assembly language routines that use the 
FPU Floating Point unit are required to 
save and restore the FPU status. If the 
assembly language routine will modify 
the FPU status, it must preserve the FPU 
status on entry by executing the 
following instruction: 

STFPS -(SP) 

and restore the status (prior to 
returning to the calling program) by 
executing the instruction: 

LDPPS (SP)+ 

Tables 4-2 and 4-3 describe the BASIC mathematical operations and 
functions. They show how each operation or function would appear in 
the BASIC language, and name the BASIC-provided routine that will 
perform it. Note that certain operations and functions require one 
routine for single precision arithmetic, a different routine for 
double precision arithmetic, and yet another for integer arithmetic. 

If you are running a BASIC system designed for double precision 
arithmetic, either the single or double precision routine names can be 
used. Either routine name will execute the double-precision routine; 
this fact allows you to use the same code for different systems 
regardless of precision. However, you must still be aware of which 
precision you are using, and ensure that the data manipulations in the 
program properly reflect the BASIC configuration on which programs are 
running. To be compatible with FORTRAN IV, you must use only the 
double precision routine names to execute the double precision 
routines. 

All routines that have a dollar sign ($) in their name must be called 
in threaded code mode. To call routines in threaded code mode, first 
call a special subroutine, $POLSH. After calling $POLSH, list the 
names of the threaded code routines you wish to call. In threaded 
code mode, each routine is executed in the order listed. All 
arguments and results are passed on the stack. Finally, list the name 
of a second special subroutine, $UNPOL, which ends threaded code mode. 

You must specify $POLSH, $UNPOL and any routine names you specify as 
globals. 

The call to $POLSH is in the following format: 

JSR R4y$P0LSH 

Figure 4-5 describes the state of the stack before and after each 
threaded code routine. 
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Table 4-2 
BASIC Mathematical Operations 



Operation 


Operator 


Meaning 


BASIC 
Equivalent 


Single- 
Precision 
Routine 


Double 

Precision 

Routine 


Addition 


+ 


Adds two floating 
point numbers 


C=A + B 


$ADR 


$ADD 


Subtraction 


— 


Subtracts one floating 
point number from 
another 


C=A - B 


SSBR 


SSBD 


Multiplication 


* 


Multiplies two floating 
point numbers 


C=A * B 


$MLR 


5MLD 






Multiplies two integers 


C%=A%*B% 


$MLI 


$MLI 


Division 


/ 


Divides one floating 
point number by 
another 


C=A / B 


SDVR 


$DVD 






Divides one integer 
by another integer 


C%=A%/B% 


$DVI 


$DVI 


Exponentiation 




Raises a floating 
point number by a 
floating point ex- 
ponent. 


C=A " B 


XFF$ 


XDD$ 






Raises a floating 
point number by an 
integer exponent. 


C=A " B% 


XFI$ 


XDIS 






Raises an integer by 
an integer exponent. 


C%=A%''B% 


XII$ 


XII$ 



Table 4-3 
BASIC Mathematical Functions 



Function 


Description 


BASIC 
Equivalent 


Single- 
Precision 
Routine 


Double 

Precision 

Routine 


Data type 
conversion 


Converts floating point number 
to integer 


B% = A 


$RI 


$DI 




Converts integer to floating 


B = A% 


$IR 


$ID 


Truncation 


Truncates a floating point 
number to a floating point 
whole number 


B=SGN(A)* 
IMT(ABS(A)) 


$INTR 


$DINT 


Sine 


Finds the sine of a radian 
value 


B=SIN(A) 


SIN 


DSIN 


Cosine 


Finds the cosine of a 
radian value 


B=COS(A) 


COS 


DCOS 




Finds the arctangent in 
radians of a number 


B=ATN(A) 


ATAN 


DATAN 


Logarithm 


Finds the natural log 
(base e) of a number 


B=LOG(A) 


ALOG 


DLOG 




Finds the common log 
(base 10) of a number 


B=LOG10(A) 


ALDGIO 


DLOGIO 


Square root 


Finds the square root of 
a number 


B=SQR(A) 


SQRT 


DSQRT 


Exponential 


Finds the value of e 
raised to a number 


B=EXP(A) 


EXP 


DEXP 
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Equivalent 


Routine 


BASIC 


Names 


Statement 


$ADR 


C=A+B 


$SBR 


C=A-B 


$MLR 


C=A*B 


$DVR 


C=A/B 


$ADD 


C=A+B 


$SBD 


C=A-B 


$IVILD 


C=A*B 


$DVD 


C=A/B 


XDD$ 


C=A''B 



$RI 



$DI 



$IR 



$ID 



$INTR 



$DINT 



B%=A 



B%=A 



Stack Before 
Execution 



$MLI 


C%=A%*B% 


B% 


$DVI 


C%=A%/B% 


A% 


Xll$ 


C%=A%'-B% 




XFIS 


C-A-^Bro 


B% 

^1 


XDI$ 


C=A'~B% 


B% 



1 



High-order FP word ■» 



Low-order FP word 



High-order FP word 



Low-order FP word 



Stack 
pointer 



High-order FP word -* 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 



High-order FP word 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 



Stack 
pointer 



Integer word 



Integer word 



Stack 
pointer 



Integer word 



High-order word 



Low-order FP word 



Stack 
pointer 



Integer word 



High-order FP word 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 



Stack 
pointer 



High-order FP word » 



Low-order FP word 



Stack 
pointer 



High-order FP word 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 



Stack 
pointer 



B=A% A% I Integer word" 



> 



Stack 
pointer 



B=A% A% I Integer wo~ 



Stack 
pointer 



B=SGN(A)* 
INT(ABS(A)) 

B=SGN(A)* 
INT(ABS(A)) 



/ [HigiT 
( I Low 



order FP word 



order FP word 



Stack 
pointer 



High-order FP word 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 



Stack 
pointer 



Stack After 
Execution 



i 



igh-order FP word -^ 



Low-order FP word 



Stack 
pointer 



High-order FP word -*- 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 



Stack 
pointer 



C% I Integer word 



> 



Stack 
pointer 



i 



igh-order FP word 



Low-order FP word 



Stack 
pointer 



High-order FP word 



Low-order FP word 



Lower-order FPword 



Lowest-order FPword 



Stack 
pointer 



B% I Integer word 



V 



Stack 
pointer 



B% i Integer word 



>- 



Stack 

pointer 



(I 



igh-order FP word 



Low-order FP word 



Stack 
pointer 



High-order FP word 


- 


Stack 
pointer 


Low-order FP word 






Lower-order FP word 




Lowest-order FP word 





High-order FP word 



Low-order FP word 



Stack 
pointer 



High-order FP word ■^- 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 



Stack 
pointer 



Note: FP stands for Floating Point 

Figure 4-5 State of Stack for Threaded Code Routines 
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As examples, consider the following segments of routines: 

Segment 1 divides an integer stored in TEMPI by an integer stored in 
TEMP2 and stores the quotient in RESULT. 

> SEGMENT :l. 



»G1...GBL 


*POL.SHyi|iUNPOL 


»$DUI 


MOV 


TEMPI !.-(SP) 




Moy 


TEMP2» -(SP) 




JSR 


R4y$P0I...SH 




. WORD 


*nvi 




♦ WORD 


*UNP0L 




MOV 


(SP)f? RESULT 





5 SET UP THE 

ii STACK 

» ENTER THREADED CODE MODE 

5 SPECIFY ROUTINE NAME 

5 LEAVE THREADED CODE MODE 
? STORE RESULT 



tempi: .word o 
temp2 .word 
result .word 



Segment 2 multiplies two single-precision floating 
FLOATA and FLOATS, and stores the product in FLOATC. 



point numbers, 



SEGMENT 2 




.GLOBL 


fPOLSH J $UNPOL » $MLR 


MOV 


FL0ATA+2» -(SP) 


MOV 


FLOATA y-(SP) 


MOV 


FLOATB+2 y - ( SP ) 


MOV 


FLOATBy-<SP) 


JSR 


R4»*P0LSH 


. WORD 


*MLR 


. WORD 


$UNPOL 


MOV 


(SP)fy FLOATC 


MOV 


(SP)+yFL0ATC+2 



yPUT FLOATA 

yON STACK 

5 PUT FLOATB 

fON STACK 

5 ENTER THREADED CODE MODE 

y SPECIFY ROUTINE NAME 

y LEAVE THREADED CODE MODE 

5 STORE RESULT 

yIN FLOATC 



FLOATA: .WORD OyO 

FLOATB : .WORD OyO 
FLOATC : .WORD OyO 



Segment 3 converts a double-precision floating point number stored 
FLOAT to an integer and stores it at INTMDW. 



at 



5 SEGMENT 3 








.GLOBL 


$POLSHy!|iUNPOL! 


>$DI 




MOV 


FL0ATf6y-(SP) 




yPUT FLOAT 


MOV 


FL0AT+4y-(SP) 




yON STACK 


MOV 


FL0AT+2y-(SP) 




yKfeEP DOING IT 


MOV 


FLOAT y -■ ( SP ) 




yDONE 


JSR 


R4y$P0LSH 




y ENTER THREADED CODE MODE 


.WORD 


*DI 




5 SPECIFY ROUTINE NAME 


.WORD 


$UNPOL 




? LEAVE THREADED CODE MODE 


MOV 


(SP)+y INTMDW 




y STORE RESULT 



float: .WORD 
INTMDW : .WORD 



OyOyOyO 




Although the foregoing examples have only one routine name after each 
call to $POLSH, you can specify any number of routine names. You must 
always follow the last of routine name with the $UNPOL routine. 
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The sine, cosine, arctangent, logarithm, square root, and exponential 
routines each use an argument list similar to the BASIC CALL argument 
list. An ALR must establish the argument list before calling the 
routine. The format of the argument list for the single-precision 
routines, SIN, COS, ATAN, ALOG, ALOGIO, SQRT, and EXP, is: 







1 1 


High-order FP word 




Pointer to argument 




Low-order FP word 







Pointer to list] R5 



Figure 4-6 Argument List for Supplied Single-Precision Routines 

The format of the argument list for the double-precision routines, 
DSIN, DCOS, DATAN, DLOG, DLOGIO, DSQRT, and DEXP is: 



High-order FP word 



Low-order FP word 



Lower-order FP word 



Lowest-order FP word 







1 



Pointer to argument 



- [Pointer to list| R5 



Figure 4-7 Argument List for Supplied Double-Precision Routines 

In both cases, the routines are called by the instruction: 

JSR PC, routine name 

The single-precision routines return the result in RO and Rlj the 
high-order word is in RO and the low order word is in Rl. 

The double-precision routines return the result in RO, Rl, R2, and R3. 
The high-order word is in RO and the low, lower, and lowest order 
words are in Rl, R2, and R3, respectively. 

You must specify as global any routine name that you call. 

These routines do not preserve any registers. 



NOTE 

You should save the initial value of R5 
before loading the pointer to the 
argument for these routines. You will 
need the saved value to execute any 
threaded code routine to access 
arguments. 



Consider the following segment of a routine that finds the square root 
of a single-precision floating point number, NUMl, and stores the 
result in NUM2: 
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r SEGMENT uh:i:ch 


FINDS SQUARE 


. (3I...0BL 


SORT 


Moy 


RSi- TEMP5 


MOU 


Rli. TEMPI 


Moy 


RO. TEMPO 


Moy 


#ARGi. R5 


JSR 


PC? SORT 


Moy 


ROy NUM2 


MOU 


Rl? NUM2+2 


MOV 


TEMPS i- R5 


MOV 


TEMPI 1- Rl 


MOV 


TEMPO? RO 



ROOT 



JSAVE 
5 SAVE 



OLD 
ANY 



VALUE 
OTHER 



OF R5 
REGISTER 



J SET UP R5 

JCALL ROUTINE 

» STORE HIGH ORDER RESULT 

y STORE LOW ORDER RESULT 

? RESTORE SAVED 

pRE(3ISTERS 



ARGt 


.WORD 


1 




.WORD 


NUM 


TEMPS 1 


.WORD 





tempi: 


.WORD 





NUMlt 


.FLT2 


A 


NUM2J 


.FI..T2 






The following example is a complete assembly language routine. This 
routine can be called by the following statement: 

CALL HYPOT(Ai-B»Ci.CZ) 

The routine calculates the value of the expression SQR(A*A+B''2) , 
assigns 'the value to C, and assigns the truncated value to C%. 

.TITLE HYPOT 
.PSECT SUBRS»RO»I 



.GLOBL 

hyptab: .byte 

.ASCII 

.EVEN 
.WORD 

.(3LDBL 
.GLOBl.. 



HYPTAB 



'HYPOT' 



HYPOT 

*ARGER , *B0MB > $POLSH r $UNPOL 
$MLR ? XFI* >. SABR y SORT > *RI 



HYPOT : 
10$: 

20*: 



30$: 



CMPB 
BEQ 
JMP 
CHPB 

BNE 



(R5)ff#4 
20* 

$ARGER 
<RS)+»*202 

60$ 



HOU 




SP » R3 


SOB 




#30 . V R3 


CMP 




R3 » RA 


HHIf; 




30* 


JSR 




Rly$BOMB 


.ASCIZ 


'STACK OUEI 


.EVE 


:n 




MOV 




■■4(R5)!iR4 


JSR 




PC , GETDSC 


BIC 




*J.6020I»R3 


CMP 




*2040i.R3 


BNF 




to* 


JSR 




PC.fiETDSC 



5 ARE THERE 4 ARGUMENTS? 

yYES. 

5N0» ISSUE ARGUMENT ERROR. 

yARE UE BEING CALLED BY BASIC -:ll 

$UTTH ARGUMENT DESCRIPTORS? 

5N0. 

;yes» check that there is enough 

5 stack space. 30. bytes should be 

? sufficient. 

5 subtract 30. from the current sp value. 

5 is it below the limit? 

SNO. 

■SYES!- ISSUE MESSAGE. 



5 GET THE POINTER TO THE FIRST ELEMENT 
vIN THE ARGUMENT DESCRIPTOR LIST. 
5 GET THE DESCRIPTOR OF THE 1ST ARGUMENT. 
SIB IT A 2 WORD REAL VALUE? 

SNO. 

JYES;. GET THE DESCRIPTOR OF THE 2ND ARGUMENT 
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60*: 



Bin 


* 1 6020.1. !-R3 


CMP 


#2040 > R3 


BNE 


:IO'4i 


JSR 


PCpHETDSC 


BIC 


fl J. 6000.1 yR3 


CMP 


t2040 p R3 


BNE 


10* 


JSR 


PC1.6ETDSC 


BTC 


*.!.6000.UR3 


CMP 


*J.022,R3 


BNE 


:1.0* 


MOV 


<R5)f S.R3 


Moy 


2(R3) .--(SPi 


MOV 


<R3>»-(SP) 


MOV 


2(R3)y-(SP) 


MOV 


<R3)»-(SP) 


JSR 


R4 y $POLSH 


itMLR 




*L)NPOL 




MOV 


<R5)fyR3 


MOV 


2CR3)»-<SP') 


MOV 


<R3)y-<SP) 


MOV 


*2»~(SP) 


JSR 


R4>$P0LSH 


XFl* 




SADR 





*UNPOI_ 



MOV 


R5»-<SP) 


MOV 


SP»R5 


TST 


(R5) + 


MOV 


R5y-<SP) 


MOV 


*:l»-(SP) 


MOV 


SP » R5 


JSR 


PC , SORT 


CMP 


<BP)f » (SP)f 


MOV 


(SP)+yR5 


MOV 


(R5)+yR3 


MOV 


ROy (R3)+ 


MOV 


Rly (R3) 


MOV 


R:ly2<SP) 


MOV 


RO y ( SP ) 


JSR 


R4 y *POLSH 


*RI 




*UNPOL 




MOV 


(SP) + yG?<R5) + 


RTS 


PC 



US IT ALSO A 2 WORD REAL? 

5 NO. 

.iGET THE DESCRTPTOR OF THE 3RD AR{31JMENT. 

ylS IT A 2 WORD REAL WtTH WR.i:T:rNn ALLOWED'! 

; NO . 

5 GET THE DESCRIPTOR OF- TNI" 4TH ARGUMENT. 

SIS IT AN INTEGER WITH WRITING ALLOWED'? 
S NO . 

liPUSH THE .I.ST ARGUMENT ON THE STACK. 
5 NOTES LOW ORDER IS PUSHED FIRST. 

SPUSH IT AGAIN BECAUSE WE WILL DO 
5A*A TO GET A"2. 

yDO THE MULTIPLY. 

yPUSH THE 2ND ARGUMENT. 



yPUSH A 2 BECAUSE WE WILL USE REAL 
5 TO INTEGER EXPONENTIATION. 

y SQUARE THE 2Nri ARGUMENT. 

yABD SQUARE OF 2NIi ARGUMENT TO SQUARE 

;0F FIRST ARGUMENT. 

5 NOW CREATE ON THE STACK THE ARGUMENTS 

5 REQUIRED BY SQRT . 

SSAVE R5. 

5 CREATE POINTER TO VALUE ON THE STACK. 



ySHOW ONLY 1 ARGUMENT TO SQRT 

yGET THE SQUARE ROOT. 

yREMOVE OLD ARGUMENTS FROM THE STACK. 

y RESTORE R5. 

y POINT TO THE 3RD ARGUMENT. 

y STORE THE REAL RESULT IN THE 

y3RD ARGUMENT. 

5N0TES SQRT RETURNED ITS RESULT IN RO Z R.L. 

5 REPLACE THE SUM OF THE SQUARES 

fWITH ITS SQUARE ROOT. 

y CONVERT TO AN INTEGER. 

y STORE THE INTEGER RESULT IN 

JTHE 4TH ARGUMENT. 

y RETURN TO THE CALLER. 



5 6ETDSC RETURNS THE NEXT ARGUMENT'S DESCRIPTOR WORD. 

y inputs: 

y r4 points to the word in the descriptor list. 

? outputs: 

5 r3 contains the descriptor word for the current argument, 

y r4 is updated to point to the next element in the list. 



CETDSC: MOV (R4>+yR3 

BIT #.l. yR3 

BNE :l.0* 

MOV (R3)yR3 

:1.0*: RTS PC 
.END 

Ready 



PGET THE DESCRIPTOR. 

ylS IT A POINTERS 

5 NO, 

SYESy GET THE ACTUAL DESCRIPTOR. 
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